feat: add sink-parity agent skill - #1689
Open
dcoric wants to merge 3 commits into
Open
Conversation
Adds a skill that encodes the cross-backend parity contract for the fs, mongo and postgres sinks: the Sink interface as the source of truth, checklists for new members, entity fields and schema changes, the semantic parity rules the compiler cannot enforce, and the verification commands. Exposed to Claude through the .claude/skills symlink and to opencode through a command stub.
jescalada
reviewed
Aug 26, 2026
jescalada
left a comment
jescalada
left a comment
Contributor
There was a problem hiding this comment.
LGTM, just a few suggestions for agent output quality 👍🏼
| ## Adding or changing a Sink member | ||
|
|
||
| 1. Add the member to the `Sink` interface with a doc comment stating its semantics (ordering, case sensitivity, empty-result shape). | ||
| 2. Implement it in `src/db/file`, `src/db/mongo`, and `src/db/postgres`. Use the mongo implementation as the reference for behaviour unless the doc comment says otherwise. |
Contributor
There was a problem hiding this comment.
Is the assumption here that usually a Mongo implementation will be added first (and the others must be filled in)? I feel this could be misleading if the agent takes it too literally...
Contributor
There was a problem hiding this comment.
I'm wondering about what the "source of truth" should even be... The Mongo implementation is by default the "official" one, but it doesn't mean it'll always be the one to use as a template, especially if new Postgres functionality is added.
| npm run format:check | ||
| ``` | ||
|
|
||
| Postgres integration tests (`npm run test:integration:postgres`) need a reachable PostgreSQL database; CI runs them in the dedicated lane. |
Contributor
There was a problem hiding this comment.
I think it'd be good to add a small testing section too:
- Explain how units vs integration tests are set up, and tell it to add both types for each adaptor
- Tell it to make sure the operations performed in each test are identical across sinks (unless N/A)
- Tell it to make sure the outputs of each test are identical across sinks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a
sink-parityskill for AI agents working on the sink backends.The skill encodes the parity contract between
src/db/file,src/db/mongoandsrc/db/postgres: theSinkinterface insrc/db/types.tsas the single source of truth, step-by-step checklists for adding interface members, entity fields and postgres schema changes, the semantic rules the compiler cannot enforce (defaults, timestamp bumps, projections, case handling, error behaviour), and the verification commands that catch drift.It is written for any agent that reads
AGENTS.md: Claude picks it up through the existing.claude/skillssymlink and opencode through the added command stub, following the same layout as the existing skills.Targeted at the
feat/postgresintegration branch since the parity obligation becomes three-way once the PostgreSQL sink lands.Resolves #1688